package org.itsolutions.javaBackup.spi.common.io;

import java.util.concurrent.BlockingDeque;

/**
 * Special buffer for data. It allows registering of buffer listeners. It extends the BlockingDeque.
 * @param <E> type of items
 * @author Tomas Fecko
 */
public interface IBuffer<E> extends BlockingDeque<E> {

	/**
	 * Method disposes the buffer and frees the space.
	 */
	void dispose();
	
	/**
	 * Method registers buffer listener.
	 * @param pBufferListener buffer listener
	 */
	void registerBufferListener(IBufferListener pBufferListener);
	
	/**
	 * Method unregisters the buffer listener.
	 * @param pBufferListener buffer listener
	 * @return true if the buffer was unregistered
	 */
	boolean unregisterBufferListener(IBufferListener pBufferListener);
	
	/**
	 * All the add/offer type operations are intercepted by this interceptor.
	 * @param pInterceptor interceptor
	 */
	void addInterceptor(IBufferInterceptor<E> pInterceptor);
	
	/**
	 * 
	 * @param pInterceptor interceptor
	 */
	void removeInterceptor(IBufferInterceptor<E> pInterceptor);
	
	/**
	 * Method add the item to buffer after the interceptor is removed. During the interceptor removal are all insert operations locked, so the item is added
	 * before the lock is released.
	 * @param pInterceptor interceptor
	 * @param pItems items to offer to buffer after the remove operation locks all the insert operations
	 */
	void removeInterceptor(IBufferInterceptor<E> pInterceptor, E... pItems);
	
	/**
	 * 
	 * @param pItem item to add
	 * @return true if inserted successfully, if false, count the discarded events
	 */
	boolean offerOrDiscardIntercepted(E pItem);
	
	/**
	 * 
	 * @param pItem item to add
	 * @param pTimeoutInMillis timeout in millis
	 * @return true if inserted successfully, if false, count the discarded events
	 */
	boolean offerOrDiscardIntercepted(E pItem, long pTimeoutInMillis);
	
	/**
	 * 
	 * @return number of discarded events
	 */
	long getNumberOfDiscardedEvents();
}






